home *** CD-ROM | disk | FTP | other *** search
/ DOpus Plus / DOpus Plus.iso / SDK / docs / rexx.doc < prev    next >
Encoding:
Text File  |  1998-10-26  |  6.5 KB  |  187 lines
  1. dopus5.library/BuildRexxMsgEx                   dopus5.library/BuildRexxMsgEx
  2.  
  3.     NAME
  4.         BuildRexxMsgEx - build a complete REXX message
  5.  
  6.     SYNOPSIS
  7.         BuildRexxMsgEx(port, extension, host, tags)
  8.                         A0       A1      D0    A2
  9.  
  10.         struct RexxMsg *BuildRexxMsgEx(struct MsgPort *, UBYTE *, UBYTE *,
  11.                                         struct TagItem *);
  12.  
  13.         struct RexxMsg *BuildRexxMsgExTags(struct MsgPort *, UBYTE *,
  14.                                             UBYTE *,Tag,...);
  15.  
  16.     FUNCTION
  17.         This routine calls CreateRexxMsgEx() to create a new ARexx message,
  18.         and then automatically initialises arguments and variables.
  19.  
  20.         The tags used to initialise the message are as follows:
  21.  
  22.             RexxTag_Arg0        - argument 0 (string in ti_Data)
  23.             RexxTag_Arg1        - argument 1
  24.                 .
  25.                 .
  26.             RexxTag_Arg15       - argument 15
  27.             RexxTag_VarName     - variable name
  28.             RexxTag_VarValue    - variable value
  29.  
  30.         The RexxTag_VarName and RexxTag_VarValue tags are always used in
  31.         pairs; the variable name must be specified before the value is set.
  32.         ti_Data points to a string which is copied to the new variable.
  33.  
  34.     INPUTS
  35.         port - reply port for message
  36.         extension - default extension
  37.         host - defaut host name
  38.         tags - tag list
  39.  
  40.     RESULT
  41.         Returns a pointer to the message if sucessful, or NULL for failure.
  42.         This message MUST be freed with a call to FreeRexxMsgEx().
  43.  
  44.     SEE ALSO
  45.         dopus5.library/CreateRexxMsgEx(), dopus5.library/FreeRexxMsgEx(),
  46.         rexxsyslib.library/CreateRexxMsg()
  47.  
  48. dopus5.library/CreateRexxMsgEx                 dopus5.library/CreateRexxMsgEx
  49.  
  50.     NAME
  51.         CreateRexxMsgEx - create a REXX message with space for variables
  52.  
  53.     SYNOPSIS
  54.         CreateRexxMsgEx(port, extension, host)
  55.                          A0       A1      D0
  56.  
  57.         struct RexxMsg *CreateRexxMsgEx(struct MsgPort *, UBYTE *, UBYTE *);
  58.  
  59.     FUNCTION
  60.         This routine creates an ARexx message that you can use to send
  61.         direct ARexx commands. It is identical to the CreateRexxMsg()
  62.         function in rexxsyslib.library, except that it also allocates
  63.         space for variables, which can be set with the SetRexxVarEx()
  64.         routine.
  65.  
  66.     INPUTS
  67.         port - reply port for message
  68.         extension - default extension
  69.         host - defaut host name
  70.  
  71.     RESULT
  72.         Returns a pointer to the message if sucessful, or NULL for failure.
  73.         This message MUST be freed with a call to FreeRexxMsgEx().
  74.  
  75.     SEE ALSO
  76.         dopus5.library/FreeRexxMsgEx(), dopus5.library/SetRexxVarEx(),
  77.         rexxsyslib.library/CreateRexxMsg()
  78.  
  79. dopus5.library/FreeRexxMsgEx                     dopus5.library/FreeRexxMsgEx
  80.  
  81.     NAME
  82.         FreeRexxMsgEx - free a REXX message created with CreateRexxMsgEx()
  83.  
  84.     SYNOPSIS
  85.         FreeRexxMsgEx(msg)
  86.                        A0
  87.  
  88.         void FreeRexxMsgEx(struct RexxMsg *);
  89.  
  90.     FUNCTION
  91.         This routine frees the supplied ARexx message. It will accept either
  92.         messages created with the CreateRexxMsgEx() (or BuildRexxMsgEx())
  93.         function, or with the CreateRexxMsg() function in rexxsyslib.library.
  94.  
  95.         Any arguments (Arg0 through to Arg15) are freed automatically.
  96.         If the message passed was created with the dopus5.library function,
  97.         any variables associated with the message are also freed.
  98.  
  99.     INPUTS
  100.         msg - message to free
  101.  
  102.     NOTES
  103.         This is the ONLY way to free a message allocated with
  104.         CreateRexxMsgEx() or BuildRexxMsgEx().
  105.  
  106.     SEE ALSO
  107.         CreateRexxMsgEx(), rexxsyslib.library/DeleteRexxMsg()
  108.  
  109. dopus5.libary/GetRexxVarEx                        dopus5.library/GetRexxVarEx
  110.  
  111.     NAME
  112.         GetRexxVarEx - get variables associated with a Rexx message
  113.  
  114.     SYNOPSIS
  115.         GetRexxVarEx(msg, varname, bufpointer)
  116.                       A0     A1         A2
  117.  
  118.         long GetRexxVarEx(struct RexxMsg *, char *, char *);
  119.  
  120.     FUNCTION
  121.         This routine is identical to the GetRexxVar() function in amiga.lib,
  122.         except that it also works with messages created with the
  123.         CreateRexxMsgEx() function. This allows you to store variables
  124.         in C-allocated ARexx messages.
  125.  
  126.     INPUTS
  127.         msg - ARexx message
  128.         varname - name of variable
  129.         bufpointer - pointer to buffer pointer
  130.  
  131.     RESULT
  132.         If the variable exists, bufpointer will contain the address of the
  133.         variable's value string. This string MUST NOT be modified.
  134.         This routine returns 0 for success. See the amiga.lib GetRexxVar()
  135.         function autodocs for other error codes.
  136.  
  137.     NOTES
  138.         Generally, the only program that will send you messages containing
  139.         variables is DOpus, or ARexx itself. This routine handles both
  140.         types of messages transparently; you can replace all your calls
  141.         to GetRexxVar() with calls to this function.
  142.  
  143.     SEE ALSO
  144.         amiga.lib/GetRexxVar(), SetRexxVarEx()
  145.  
  146. dopus5.libary/SetRexxVarEx                        dopus5.library/SetRexxVarEx
  147.  
  148.     NAME
  149.         SetRexxVarEx - set variables associated with a Rexx message
  150.  
  151.     SYNOPSIS
  152.         SetRexxVarEx(msg, varname, value, length)
  153.                       A0     A1      D0      D1
  154.  
  155.         long SetRexxVarEx(struct RexxMsg *, char *, char *, long);
  156.  
  157.     FUNCTION
  158.         This routine is identical to the SetRexxVar() function in amiga.lib,
  159.         except that it also works with messages created with the
  160.         CreateRexxMsgEx() function. This allows you to store variables
  161.         in C-allocated ARexx messages.
  162.  
  163.     INPUTS
  164.         msg - ARexx message
  165.         varname - name of variable
  166.         value - value of variable, or 0 to delete variable
  167.         length - length of value string, -1 for strlen()
  168.  
  169.     RESULT
  170.         The variable will be created (if it does not already exist) and
  171.         its value set. The supplied value is copied by this function.
  172.         This routine returns 0 for success. See the amiga.lib SetRexxVar()
  173.         function autodocs for other error codes.
  174.  
  175.     NOTES
  176.         This allows you to send ARexx messages to DOpus that contain stem
  177.         variables. This routine also works with messages created with
  178.         the rexxsyslib.library CreateRexxMsg() function, and handles both
  179.         types transparently. You can only send variables to DOpus if the
  180.         message was created with the CreateRexxMsgEx() function.
  181.         You can replace all your calls to SetRexxVar() with calls to this
  182.         function.
  183.  
  184.     SEE ALSO
  185.         amiga.lib/SetRexxVar(), GetRexxVarEx()
  186.  
  187.